Crate ion_c_sys

source ·
Expand description

Provides basic bindings for Ion C

These bindings are created with bindgen and are considerably low-level.

Examples

Using ion-c-sys directly can be a pretty verbose affair, and requires checking the error code for most calls. This crate provides the result module to make it easier to integrate with std::result::Result with respect to the iERR that Ion C functions generally return. Specifically, any low-level IonC function that returns iERR should be called with the ionc! macro to facilitate Result<(), IonCError> conversion.

This library provides smart pointers over the low-level reader/writer pointers, and should generally be used, especially with Result handling code. These types provide some facade over Ion C, but only for the most generally used APIs. See:

Ion Reader

Here is an end-to-end example of reading some Ion data.

let mut reader = IonCReaderHandle::try_from("{a:2}")?;

// step to the struct
assert_eq!(ION_TYPE_STRUCT, reader.next()?);
// step into the struct
reader.step_in()?;
// step to the field
assert_eq!(ION_TYPE_INT, reader.next()?);
// retrieve the field name
assert_eq!("a", reader.get_field_name()?.as_str());
// read the integer value
assert_eq!(2, reader.read_i64()?);
// step to the end of the struct
assert_eq!(ION_TYPE_EOF, reader.next()?);
// step out of the struct
reader.step_out()?;
// step to the end of the stream
assert_eq!(ION_TYPE_EOF, reader.next()?);

Ion Writer

Here is an end-to-end example of writing some Ion data.

// output buffer
let mut buf: Vec<u8> = vec![0; 128];
let len = {
    let mut writer = IonCWriterHandle::new_buf_mode(buf.as_mut(), WriterMode::Binary)?;
    // start a list
    writer.start_container(ION_TYPE_LIST)?;
    // write some integers
    for n in 0..4 {
        writer.write_i64(n * 2)?;
    }
    // end the list
    writer.finish_container()?;
    // start a struct
    writer.start_container(ION_TYPE_STRUCT)?;
    {
        // write a string
        writer.field("name").annotations(&["version"]).write_string("💩")?;
    }
    // end the struct
    writer.finish_container()?;
    // finish writing
    writer.finish()?
};

// make sure the bytes match what we expect
let expected: &[u8] = &[
    0xE0, 0x01, 0x00, 0xEA,         // IVM
    0xB7,                           // LIST size 7
    0x20,                           // INT 0
    0x21, 0x02,                     // INT 2
    0x21, 0x04,                     // INT 4
    0x21, 0x06,                     // INT 6
    0xD9,                           // STRUCT size 8
    0x84,                           // field "name" (sid 4)
    0xE7, 0x81, 0x85,               // annotation "version" (sid 5)
    0x84, 0xF0, 0x9F, 0x92, 0xA9,   // STRING 💩
];
assert_eq!(expected.len(), len);
assert_eq!(expected, &buf[0..len]);

Re-exports

Modules

  • decimal
    Provides higher-level APIs for ION_DECIMAL
  • int
    Provides higher-level APIs for ION_INT
  • reader
    Provides higher-level APIs for Ion C’s hREADER.
  • result
    Provides convenient integration with Error and Result for Ion C.
  • string
    Provides higher-level APIs for borrowing str slices safely from Ion C.
  • timestamp
    Provides integration between ION_TIMESTAMP and chrono::DateTime.
  • writer
    Provides higher-level APIs for Ion C’s hWRITER.

Macros

  • ionc
    Macro to transform Ion C error code expressions into Result<(), IonCError>. Higher-level facades over Ion C functions could map this to Result<T, IonCError> or the like.

Structs

Constants

Statics

Functions

Type Definitions

Unions